Restructure execution modes #2565
Conversation
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
|
One or more of the following people are relevant to this code:
|
Co-authored-by: abbycross <[email protected]>
| @@ -5,73 +5,169 @@ description: An overview of the available execution modes in Qiskit Runtime; ses | |||
| --- | |||
| # Introduction to Qiskit Runtime execution modes | |||
|
|
|||
| There are several ways to run workloads, depending on your needs. | |||
| There are several ways to run workloads, depending on your needs. Execution modes determine how your jobs are scheduled, and choosing the right execution mode allows your jobs to run efficiently within your budget. | |||
There was a problem hiding this comment.
I think we need a little bit more meat on the intro paragraph. Taking from the execution mode blog, how about something like
When Qiskit Runtime was first introduced, users could only execute circuits as individual jobs. As different types of quantum workloads emerge, we recognized the need for different scheduling strategies. The execution modes determine how your jobs are scheduled, and choosing the right execution mode allows your workload to run efficiently within your budget. There are three execution modes: job mode, session mode, and batch mode.
|
|
||
| <Admonition type="note"> | ||
| The `mode` option requires `qiskit-ibm-runtime` 0.24 or later. | ||
| The queuing time does not decrease for the first job submitted within a session or batch. Therefore, sessions and batches do not provide any benefits when running a single job. Additionally, sessions and batches do not work on simulators because simulators do not have a queue. |
There was a problem hiding this comment.
Additionally, sessions and batches do not work on simulators because simulators do not have a queue.
Shouldn't this be moved to the session/batch sections?
|
|
||
| ## Batch mode | ||
|
|
||
| A multi-job manager for efficiently running an experiment that is comprised of bundles of independent jobs. Use batch mode to submit multiple primitive jobs simultaneously. |
There was a problem hiding this comment.
Again we can take wording from the blog to give more info on this. Something like
A multi-job manager for efficiently running experiments comprising multi-job workloads. These workloads are made up of independently executable jobs that have no conditional relationship with each other. With batch mode, users submit their jobs all at once. The system parallelizes or threads the pre-processing step of each primitive job to more tightly package quantum execution across jobs, and then runs the quantum execution of each job in quick succession to deliver the most efficient results.
| <Admonition type="note"> | ||
| When batching, jobs are not guaranteed to run in the order they are submitted. Also, while your batch jobs will run as closely together as possible, they don't get exclusive access to the backend. Therefore, your batch jobs might run in parallel with other users' jobs if there is enough processing capacity on the QPU. Additionally, QPU calibration jobs could run between the batched jobs. | ||
| </Admonition> |
There was a problem hiding this comment.
Can we move this to after the diagram? Having it before makes it look like it's part of the Note.
| When batching, jobs are not guaranteed to run in the order they are submitted. Also, while your batch jobs will run as closely together as possible, they don't get exclusive access to the backend. Therefore, your batch jobs might run in parallel with other users' jobs if there is enough processing capacity on the QPU. Additionally, QPU calibration jobs could run between the batched jobs. | ||
| </Admonition> | ||
|
|
||
|  |
There was a problem hiding this comment.
I feel the picture in the Usage section would be very useful to help people understand what a batch is.
|
|
||
| **Interactive timeout (ITTL)** - This value cannot be configured. If no jobs are queued for the active session or batch within that window, the workload is temporarily deactivated. A job submitted to the session or batch reactivates the deactivated workload if the maximum timeout value has not been reached. | ||
|
|
||
| For full details about these values, including how to determine the ITTL value, review the [Maximum execution time guide.](/guides/max-execution-time) |
There was a problem hiding this comment.
I find it a bit confusing that when reading this guide on execution mode, there is a link to the max execution time page, which has a link back to this guide...
| - If you partition your workload into multiple jobs and run them in batch mode, you can get results from individual jobs, which makes them more flexible to work with. For example, if a job's results don't meet your expectations, you can cancel the remaining jobs. Also, if one job fails, you can re-submit it instead of re-running the entire workload. | ||
| - **Session** | ||
| - Dedicated and exclusive access to the QPU during the session active window. | ||
| - Can run multiple experiments simultaneously. |
There was a problem hiding this comment.
You can technically run multiple experiments simultaneously in batch as well, as long as they are not iterative workloads.
Instead of this line, perhaps we can say "all the benefits you get from batch mode". Multiple people have asked me if parallel compilation only happens in batch and not session, since it's not explicitly listed under session.
|
|
||
| <span id="sessions-versus-batch-usage" /> | ||
|
|
||
| ## Choose batch or sessions mode | ||
| ## Choose the right execution mode |
There was a problem hiding this comment.
This page feels a bit too long. Maybe we can move this part to a separate page?
| To find the usage time for your batch or session, in `qiskit-ibm-runtime` 0.30 or later, run `batch.usage()` or `session.usage()`. When using an older version of `qiskit-ibm-runtime` (>= 0.23 and < 0.30), the usage can be still be found in `session.details()["usage_time"]` and `batch.details()["usage_time"]`. | ||
|
|
||
| If you call the REST API directly, the usage time is the `elapsed_time` value returned by the `GET /sessions/{id}` endpoint, for both batch and session workloads. | ||
|
|
||
| Your usage has different impacts, depending on which channel you're using: | ||
|
|
||
| - For Qiskit Runtime on IBM Cloud users, the usage determines how much the job costs. See [Manage cost](/guides/manage-cost#manage-cost) for details. | ||
| - For IBM Quantum Platform users, this translates to shares. The [fair-share scheduler](/guides/fair-share-scheduler) prioritizes instances with the most shares left. Thus, the higher your usage, the longer your next job stays in the queue. |
There was a problem hiding this comment.
I feel usage is an important topic and having it under Introduction to execution modes is not intuitive. Maybe this can be moved to Estimate job runtime, especially since it already has a View the estimated workload (job) usage on IBM Quantum Platform topic.
|
|
||
| The above are general guidelines, and you should tune your workload to find the optimal ratio, especially when using sessions. For example, if you are using a session to get exclusive access to a backend, consider breaking up large jobs into smaller ones and running them in parallel. This might be more cost-effective because it can reduce wall clock time. | ||
| In addition, if you use [PEA](/guides/error-mitigation-and-suppression-techniques#pea) or [PEC](/guides/error-mitigation-and-suppression-techniques#pec), you can learn the noise model once and apply it to subsequent jobs when running in dedicated session. This usually doesn't work with batch or job mode because the noise model could become stale by the time the next iteration runs. |
There was a problem hiding this comment.
learn the noise model should link to https://docs.quantum.ibm.com/guides/noise-learning
closes #2133
preview: https://qiskit.github.io/documentation/pr-2565/guides/execution-modes